文档编写

编写之前

Github提供很好的展示方式 , 使用GFM(Github Flavored Markdown)自有语法完成在线生成文档 . 在线文档可以在GitHub中提供直接阅读 . NW.js提供相关文档为开发人员 . 提交文档前确保无误可读 .

NW.js文档网站使用MkDocs生成 , MkDocs使用的语法与GFM略有不同 . GFM中的语法在MkDocs中可能不能够使用 , 但MkDocs所有语法GFM都支持 . 内链接需要使用.md作为文件后缀 , 不能像这样[Build NW.js](Build NW.js) . GitHub中 , 链接不能使用原因为Build NW.js对应的.md文件不存在 . 内链接需要使用.md作为后缀 .

官方文档

本地设备中查看文档需要使用Python以及安装以下依赖:

pip install mkdocs pygments pymdown-extensions

NW.js根目录中运行命令:

mkdocs serve

浏览器中打开地址http://localhost:8000/ .

样例文档样式

以下部分为最小的NW.js文档样例格式:

# 模块名 {: .doctitle}

---

[TOC]

使用描述以及其他模块详细说明 . 

## Module.staticMethod(arg1, arg2)

* `arg1` `{String}` `arg1`参数说明
* `arg2` `{Object}` `arg2`参数说明
  * `isSet` `{Boolean}` 属性说明
* Returns `{Type}` 返回值说明

方法详细说明 . 

## inst.method(arg1, arg2)

## Event: eventName(arg1, arg2)

[必须] 文档使用#为页面标题 , ##和###标识段落说明头 , 分别是一二三级标题 , 不能使用=======或------- .
[必须] 文档页面标题右侧需要添加{: .doctitle}说明文档标题样式类名 .
[必须] 文档页面标题后添加--- .
[必须] ---之后添加[TOC] .
[必须] 代码块使用(`)进行引用 , 标题中代码除外 .
[必须] 代码块指定具体使用的语言 .
标题中说明方法或者属性[必须]使用小写名称 , 比如win.resizeTo(x,y) , 而不使用Window.resizeTo(x,y)
标题中事件[必须]写为Event: eventName(args...)
[必须] 方法必须提供参数以及返回值说明 , 包括变量名称 , 类型 , 格式为({TypeName}) , 是否为必选参数 .

检查项

[ ] 遵守样例文档样式中的格式说明 .
[ ] 确保新文档页面添加到mkdocs.yml
[ ] 确保新文档页面在GitHub中可读
[ ] 确保页面连接可用
[ ] 添加编写人名称和邮件到文档贡献者

标记扩展

NW.js文档网站使用一下标记扩展生成文档 . 参考根目录中的mkdocs.yml获取详细配置 .

markdown.extensions.toc
markdown.extensions.admonition
markdown.extensions.smarty
markdown.extensions.nl2br
markdown.extensions.codehilite
pymdownx.extra
pymdownx.inlinehilite
pymdownx.magiclink
pymdownx.tilde
pymdownx.caret
pymdownx.smartsymbols
pymdownx.githubemoji
pymdownx.tasklist
pymdownx.progressbar
pymdownx.headeranchor
pymdownx.arithmatex
pymdownx.mark
pymdownx.critic